<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>iCal-to-Presence Gateway - Program Documentation</title>
<meta name="author" content="Milind,John,Suhas">
<meta name="keywords" content="ical,presence,gateway,caldav">
<meta name="description" content="Detailed description of gateway.">

<style type="text/css">
.cmd {
	font-family: courier new;
	font-size: 12px;
}

.default {
	font-family: courier new;
	font-size: 12px;
	font-weight: bold;
}
</style>
</head>
<body bgcolor=white>

<h1>iCal-to-Presence Gateway - Program Documentation</h1>
<address>
John Morales<br>
Columbia University<br>
New York, NY 10027<br>
USA<br>
<a href="mailto:jm2873@columbia.edu">jm2873@columbia.edu</a>
</address>
<p>
<address>
Milind Nimesh<br>
Columbia University<br>
New York, NY 10027<br>
USA<br>
<a href="mailto:mn2353@columbia.edu">mn2353@columbia.edu</a>
</address>
<p>
<address>
Suhas Suhas<br>
Columbia University<br>
New York, NY 10027<br>
USA<br>
<a href="mailto:ss3474@columbia.edu">ss3474@columbia.edu</a>
</address>
<p>

<h2>Abstract</h2>

<p>This report describes a gateway between an iCalendar calendar server that implements CalDAV and a
SIP Presence server. Users gain access to the gateway service by registering their calendar account
with the gateway through a web interface. The gateway then syncs their calendar events with the
Presence server. Periodic polling of the calendar server provides automated busy tracking
for those subscribing to user's presence information</p>

<p>The gateway was implemented in Java and leverages the ical4j, ical4j-connector, jain-sip, and various Apache libraries for making HTTP-like requests and logging.</p>

<h2>System Requirements</h2>

<ul>
  <li>Platform Independent (JVM)</li>
  <li>Network connection</li>
  <li>Database (Currently using MySQL)</li>
  <li>Java Servlet Container (e.g., Tomcat)</li>
</ul>

<h2>Quick-Start Installation and Running</h2>
<ul>
   <li>Extract compressed archive ical-to-presence-gateway_0.0.1.tar.bz2 to directory DIR and move to that directory.</li>

		<br>
		<span class="cmd">$> tar -C DIR/ -jxf ical-to-presence-gateway_0.0.1.tar.bz2</span><br>
		<span class="cmd">$> cd DIR/ical-gateway/</span><br><br>

   <li>Rename the sample configuration file to the correct name</li>

		<br><span class="cmd">$> cp conf/gateway.conf-sample conf/gateway.conf</span><br><br>

   <li>Start the server using the run.sh script</li>

	<br><span class="cmd">$> ./run.sh</span><br>

</ul>

<p>The server will start, displaying something similar to the following:</p>

<span class="cmd">
$> ./run.sh -q<br/>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.Main &lt;init&gt;<br>
INFO: Starting up Gateway: Wed Dec 17 16:28:48 EST 2008<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.Main doBootstrap<br>
INFO: Loading configurations from gateway.conf...<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.Main doBootstrap<br>
INFO: Building MySQL database connection.<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.DBEngine getAllRegisteredUsers<br>
INFO: Retreiving registered users from database.<br>
log4j:WARN No appenders could be found for logger (org.apache.commons.httpclient.params.DefaultHttpParams).<br>
log4j:WARN Please initialize the log4j system properly.<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.Main doBootstrap<br>
INFO: Initializing SIP Layer...<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.presence.SipLayer &lt;init&gt;<br>
INFO: SIP stack initialized.<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.Main doBootstrap<br>
INFO: Bootstrap done, setting up logger to start writing to file...<br>
Dec 17, 2008 4:28:48 PM edu.columbia.voip.server.RegistrationThread run<br>
INFO: Starting up registration thread<br>
</span>

<h2>Advanced Configuration</h2>

The iCal gateway includes a <span class="cmd">gateway.conf-sample</span> that uses all the simplest and
most common configurations settings. It is likely (especially for a production
system) that these configuration parameters should be tweaked. The file itself
briefly describes each of the parameters; this section will describe each of
these configuration parameters in more detail:

<ul>
<li>RegistrationListenPort</li>

<p><span class="cmd">
# Listening TCP port for registrations. Registration servlet will make TCP<br>
# connection to this port to pass server new registration account.<br>
# <span class="default">(default: 1783)</span><br>
RegistrationListenPort 1783<br>
</span></p>

<li>ThreadPoolSize</li>
<p><span class="cmd">
# Size of the thread pool for polling registered user's calendar accounts<br>
# <span class="default">(default: 30)</span><br>
ThreadPoolSize 30<br>
</span></p>

<li>PollInterval</li>
<p><span class="cmd">
# Interval between pollings of the iCalendar server. Time measured in<br>
# milliseconds<br>
# <span class="default">(default: 30000, e.g., 30 secs)</span><br>
PollInterval 30000<br>
</span></p>

<li>LogfileName</li>
<p><span class="cmd">
# Name of server java.util.Logger logfile<br>
# <span class="default">(default: gatewayical.log)</span><br>
LogfileName gatewayical.log<br>
</span></p>

<li>LogfileLevel</li>
<p><span class="cmd">
# Level of debug info saved to the logfile.<br>
# Possible values include: finest, fine, info, severe, warning, off<br>
# <span class="default">(default: info)</span><br>
LogfileLevel info<br>
</span></p>

<li>ICalendarHost</li>
<p><span class="cmd">
# Hostname of the Apple iCalendar server<br>
# <span class="default">(default: calendar.cs.columbia.edu)</span><br>
ICalendarHost calendar.cs.columbia.edu<br>
</span></p>

<li>ICalendarPort</li>
<p><span class="cmd">
# Destination port of the calendar server<br>
# <span class="default">(default: 8443)</span><br>
ICalendarPort 8443<br>
</span></p>

<li>ICalendarUseSSL</li>
<p><span class="cmd">
# Is the calendar server expecting SSL connections<br>
# <span class="default">(default: true)</span><br>
ICalendarUseSSL true<br>
</span></p>

<li>PresenceHost</li>
<p><span class="cmd">
# Hostname of the Presence server where notifications based upon user's<br>
# calendars should be sent.<br>
# <span class="default">(default: presence.cs.columbia.edu)</span><br>
PresenceHost presence.cs.columbia.edu<br>
</span></p>

<li>PresencePort</li>
<p><span class="cmd">
# Destination port of the presence server<br>
# <span class="default">(default: 5060)</span><br>
PresencePort 5060<br>
</span></p>

<li>PresenceUseSSL</li>
<p><span class="cmd">
# Is the presence server expecting SSL connections<br>
# <span class="default">(default: false)</span><br>
PresenceUseSSL false<br>
</span></p>

<li>PresenceUsername</li>
<p><span class="cmd">
# Username for accessing presence server<br>
# <span class="default">(default: presence)</span><br>
PresenceUsername presence<br>
</span></p>

<li>PresenceTimeout</li>
<p><span class="cmd">
# Time (in msec) to wait for a response from the presence server before<br>
# assuming the server is done (fatal exception).<br>
# <span class="default">(default: 500)</span><br>
PresenceTimeout 500<br>
</span></p>

<li>MysqlHost</li>
<p><span class="cmd">
# Hostname where the mysql server is running<br>
# <span class="default">(default: localhost)</span><br>
MysqlHost localhost<br>
</span></p>

<li>MysqlRegistrationDB</li>
<p><span class="cmd">
# Name of mysql database for storing the gateway registrations.<br>
# <span class="default">(default: icalgateway)</span><br>
MysqlRegistrationDB icalgateway<br>
</span></p>

<li>MysqlPort</li>
<p><span class="cmd">
# Mysql server's listening port. (most likely won't need to change this)<br>
# <span class="default">(default: 3306)</span><br>
MysqlPort 3306<br>
</span></p>

<li>MysqlUsername</li>
<p><span class="cmd">
# Mysql username for database MysqlRegistrationDB<br>
# <span class="default">(default: root)</span><br>
MysqlUsername root<br>
</span></p>

<li>MysqlPassword</li>
<p><span class="cmd">
# Password for MysqlUsername<br>
# <span class="default">(default: &lt;none&gt;, i.e., commented out)</span><br>
# MysqlPassword mypassword<br>
</span></p>

</ul>
<br>
<h2>High-level Usage</h2>

<p>Users must register their iCalendar server information (host, port, URI) and credentials (username, password)
with the gateway's MySQL database in order to use the service. Registration is provided via a web form
that prompts the user for the relevant information. The the form is submitted, the servlet adds the new gateway account to the registration database as well as creates a new entry in the presence database from which watchers may choose to subscribe.
Once registered, the user's record is read by the server's bootstrap routine during server startup. The bootstrap
process accesses the database to obtain all the relevant info for registered
users, saving a data structure in memory for each such "account".</p>

<img src="images/registration_screenshot.png" alt="registration web interface"></img>

<p>Figure 1: Registration UI</p>


<h2>Possible Enhancements and Limitations</h2>
 <ol>
   <li>Due to the limitations of the Apple iCalendar server (and the iCalendar
   model in general), there is no way to escape polling as the primary means
   for obtaining calendar information. It would be fantastic for future
   implementations of calendar servers to support a push method rather than
   a pull.</li>
   <li>We suspect there are performance optimizations possible with regard to
   the number of threads created and destroyed. This seems like it could become
   a definitely scalability bottleneck as registered gateway users approach
   100s or 1000s.
 </ol>


<h2>How to build Gateway</h2>
 <p>For *NIX and win32 platforms, please perform an ANT build:</p>
 <span class="cmd">
 $> cd ical-gateway/<br>
 $> ant build<br>
</span>
<br><br>

</body>
</html>
